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 LocationLink to section

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

Custom locationLink to section

Override the default location by setting the MXBAI_CONFIG_PATH environment variable:

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

Configuration PrecedenceLink to section

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. Environment variables - System environment settings (e.g., MXBAI_API_KEY, MXBAI_BASE_URL, MXBAI_CONFIG_PATH, MXBAI_DEBUG)
  3. Manifest entry - File-specific settings in manifest files (only applies to manifest uploads)
  4. Manifest defaults - Default settings in manifest files (only applies to manifest uploads)
  5. Config file - User configuration file settings
  6. 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 KeyLink to section

CommandLink to section

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

OptionsLink to section

  • <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)

ExamplesLink to section

# 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 KeysLink to section

CommandLink to section

mxbai config keys list

ExamplesLink to section

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

Remove API KeyLink to section

CommandLink to section

mxbai config keys remove <name>

OptionsLink to section

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

ExamplesLink to section

# 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 KeyLink to section

CommandLink to section

mxbai config keys set-default <name>

OptionsLink to section

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

ExamplesLink to section

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

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

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

Set Configuration ValuesLink to section

CommandLink to section

mxbai config set <key> <value>

ExamplesLink to section

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

# Deprecated - contextualization is now configured at the store level
# mxbai config set defaults.upload.contextualization true

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

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

Get Configuration ValuesLink to section

CommandLink to section

mxbai config get [key]

ExamplesLink to section

# View all configuration
mxbai config get

# View specific configuration section
mxbai config get defaults.upload

# View specific setting
mxbai config get api_key

Configuration OptionsLink to section

API AuthenticationLink to section

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 DefaultsLink to section

Configure default options for file uploads:

Processing StrategyLink to section

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

ContextualizationLink to section

Include metadata in chunk embeddings to improve search relevance.

  • Config key: defaults.upload.contextualization
  • Default: false
  • Valid values: true, false
# Deprecated - this setting is now ignored
mxbai config set defaults.upload.contextualization true

Parallel UploadsLink to section

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

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

Search DefaultsLink to section

Configure default search behavior:

Number of ResultsLink to section

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

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

Result RerankingLink to section

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

Store AliasesLink to section

Create shortcuts for frequently used stores:

# Create aliases for long 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 store upload "My Documentation Store" "*.md"
mxbai store upload docs "*.md"

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

Default ConfigurationLink to section

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

{
  "api_keys": {},
  "defaults": {
    "upload": {
      "strategy": "fast",
      "contextualization": false, // Deprecated - now configured at store level
      "parallel": 100
    },
    "search": {
      "top_k": 10,
      "rerank": false
    },
    "api_key": undefined
  },
  "aliases": {}
}

Configuration File StructureLink to section

After customization, your configuration file might look like:

{
  "api_keys": {
    "work": "mxb_xxxxx",
    "personal": "mxb_xxxxx"
  },
  "defaults": {
    "upload": {
      "strategy": "high_quality",
      "contextualization": true, // Deprecated - now configured at store level
      "parallel": 10
    },
    "search": {
      "top_k": 20,
      "rerank": true
    },
    "api_key": "work"
  },
  "aliases": {
    "docs": "My Documentation Store",
    "kb": "Company Knowledge Base"
  }
}

Common Configuration ExamplesLink to section

Development SetupLink to section

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 SetupLink to section

Optimize for quality and accuracy:

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

# Note: contextualization is now configured at the store level, not per-upload
# 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 SetupLink to section

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

DebuggingLink to section

Enable debug output to troubleshoot issues:

# Via command flag
mxbai store list --debug

# Via environment variable
export MXBAI_DEBUG=true
mxbai store list

# Debug shows:
# - Configuration resolution
# - Error stack traces
Last updated: March 17, 2026

Installation & Setup

Install the mxbai CLI on your system and get started with Mixedbread's AI services.

Store Management

Create, list, get, update, and delete stores.

On this page

Configuration File Location
Custom location
Configuration Precedence
Add API Key
Command
Options
Examples
List API Keys
Command
Examples
Remove API Key
Command
Options
Examples
Set Default API Key
Command
Options
Examples
Set Configuration Values
Command
Examples
Get Configuration Values
Command
Examples
Configuration Options
API Authentication
Upload Defaults
Processing Strategy
Contextualization
Parallel Uploads
Search Defaults
Number of Results
Result Reranking
Store Aliases
Default Configuration
Configuration File Structure
Common Configuration Examples
Development Setup
Production Setup
CI/CD Setup
Debugging