Mixedbread

Configuration

The mxbai CLI provides flexible configuration management to set defaults, store credentials, and create aliases for common operations. Configuration is stored in platform-specific locations and can be managed using the mxbai config commands.

Configuration File Location

~/Library/Application Support/mixedbread/config.json

Custom location

Override the default location by setting the MXBAI_CONFIG_PATH environment variable:

export MXBAI_CONFIG_PATH=/path/to/your/config.json

Configuration Precedence

When using the CLI, configuration values are resolved in the following order (highest to lowest priority):

  1. Command-line flags - Direct CLI options (e.g., --strategy high_quality)
  2. Manifest entry - File-specific settings in manifest files (only applies to manifest uploads)
  3. Manifest defaults - Default settings in manifest files (only applies to manifest uploads)
  4. Config file - User configuration file settings
  5. Built-in defaults - CLI default values

This allows flexible configuration while maintaining predictable behavior. For example:

  • If you set defaults.upload.strategy = "high_quality" in your config file, but use --strategy fast on the command line, the command-line flag takes precedence.
  • When using manifest files, individual file settings override the manifest defaults, which in turn override your config file settings.

Add API Key

Command

mxbai config keys add <api-key> [name]

Options

  • <api-key> - The API key to add (required, must start with mxb_)
  • [name] - Optional name for the API key (if not provided, you will be prompted)

Examples

# Add API key with a name
mxbai config keys add mxb_xxxxx work

# Add API key without name (will prompt for name)
mxbai config keys add mxb_xxxxx

List API Keys

Command

mxbai config keys list

Examples

# List all stored API keys
mxbai config keys list
# Output:
#   work
# * personal (default)

Remove API Key

Command

mxbai config keys remove <name>

Options

  • <name> - The name of the API key to remove (required)
  • --yes, -y - Skip confirmation prompt

Examples

# Remove an API key by name
mxbai config keys remove personal

# Remove an API key by name without confirmation
mxbai config keys remove personal --yes

Set Default API Key

Command

mxbai config keys set-default <name>

Options

  • <name> - The name of the API key to set as default (required)

Examples

# Set default API key
mxbai config keys set-default work

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

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

Set Configuration Values

Command

mxbai config set <key> <value>

Examples

# Set upload defaults
mxbai config set defaults.upload.strategy high_quality
mxbai config set defaults.upload.contextualization true
mxbai config set defaults.upload.parallel 10

# Set search defaults
mxbai config set defaults.search.top_k 20
mxbai config set defaults.search.rerank true

# Create vector store aliases
mxbai config set aliases.docs "My Documentation"
mxbai config set aliases.kb "Knowledge Base"

Get Configuration Values

Command

mxbai config get [key]

Examples

# View all configuration
mxbai config get

# View specific configuration section
mxbai config get defaults.upload

# View specific setting
mxbai config get api_key

Configuration Options

API Authentication

The CLI supports multiple API keys for different organizations or environments. Use the keys subcommand to manage them:

mxbai config keys add mxb_xxxxx
  • Required format: Must start with mxb_
  • Security: Stored locally in your user directory
  • Multi-key support: Add multiple keys with names for easy switching

Upload Defaults

Configure default options for file uploads:

Processing Strategy

Choose between fast processing for speed or high quality processing for better search results.

  • Config key: defaults.upload.strategy
  • Default: fast
  • Valid values: fast, high_quality
mxbai config set defaults.upload.strategy high_quality

Contextualization

Enable context preservation to maintain relationships between document sections for more accurate search results.

  • Config key: defaults.upload.contextualization
  • Default: false
  • Valid values: true, false
mxbai config set defaults.upload.contextualization true

Parallel Uploads

Control how many files are uploaded simultaneously to optimize for your network and system resources.

  • Config key: defaults.upload.parallel
  • Default: 5
  • Valid range: 1 to 20
mxbai config set defaults.upload.parallel 10

Search Defaults

Configure default search behavior:

Number of Results

Set how many search results to return by default when searching your vector stores.

  • Config key: defaults.search.top_k
  • Default: 10
  • Valid range: 1 to 100
mxbai config set defaults.search.top_k 20

Result Reranking

Enable AI-powered reranking to reorder search results based on relevance, improving the quality of top results.

  • Config key: defaults.search.rerank
  • Default: false
  • Valid values: true, false
mxbai config set defaults.search.rerank true

Vector Store Aliases

Create shortcuts for frequently used vector stores:

# Create aliases for long vector store names
mxbai config set aliases.docs "My Documentation Store"
mxbai config set aliases.kb "Company Knowledge Base"
mxbai config set aliases.proj "Project Files"

Then use aliases in commands:

# Instead of: mxbai vs upload "My Documentation Store" "*.md"
mxbai vs upload docs "*.md"

# Instead of: mxbai vs search "Company Knowledge Base" "how to get started"
mxbai vs search kb "how to get started"

Default Configuration

When no configuration is set, the CLI uses these default values:

{
  "api_keys": {},
  "defaults": {
    "upload": {
      "strategy": "fast",
      "contextualization": false,
      "parallel": 5
    },
    "search": {
      "top_k": 10,
      "rerank": false
    },
    "api_key": null
  },
  "aliases": {}
}

Configuration File Structure

After customization, your configuration file might look like:

{
  "api_keys": {
    "work": "mxb_xxxxx",
    "personal": "mxb_xxxxx"
  },
  "defaults": {
    "upload": {
      "strategy": "high_quality",
      "contextualization": true,
      "parallel": 10
    },
    "search": {
      "top_k": 20,
      "rerank": true
    },
    "api_key": "work"
  },
  "aliases": {
    "docs": "My Documentation Store",
    "kb": "Company Knowledge Base"
  }
}

Common Configuration Examples

Development Setup

Optimize for speed during development:

# Fast uploads for quick iterations
mxbai config set defaults.upload.strategy fast
mxbai config set defaults.upload.parallel 5

# More search results for exploration
mxbai config set defaults.search.top_k 15

# Create development aliases
mxbai config set aliases.dev "Development Docs"
mxbai config set aliases.test "Test Data"

Production Setup

Optimize for quality and accuracy:

# High quality processing for better results
mxbai config set defaults.upload.strategy high_quality
mxbai config set defaults.upload.contextualization true

# Balanced search configuration
mxbai config set defaults.search.top_k 10
mxbai config set defaults.search.rerank true

# Production aliases
mxbai config set aliases.prod "Production Knowledge Base"
mxbai config set aliases.docs "Official Documentation"

CI/CD Setup

Configure for automated environments:

# Store API key (usually from environment variable)
mxbai config keys add $MXBAI_API_KEY ci

# Fast processing for CI pipelines
mxbai config set defaults.upload.strategy fast
mxbai config set defaults.upload.parallel 10

Debugging

Enable debug output to troubleshoot issues:

# Via command flag
mxbai vs list --debug

# Via environment variable
export MXBAI_DEBUG=true
mxbai vs list

# Debug shows:
# - Configuration resolution
# - Error stack traces

Last updated: August 27, 2025