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

Command-line flags - Direct CLI options (e.g., --strategy high_quality)
Manifest entry - File-specific settings in manifest files (only applies to manifest uploads)
Manifest defaults - Default settings in manifest files (only applies to manifest uploads)
Config file - User configuration file settings
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.

Set Configuration Values

Command

mxbai config set <key> <value>

Examples

# Set API key
mxbai config set api_key mxb_xxxxx

# 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

Store your API key securely in the config file:

mxbai config set api_key mxb_xxxxx

Required format: Must start with mxb_
Security: Stored locally in your user directory

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_key": null,
  "defaults": {
    "upload": {
      "strategy": "fast",
      "contextualization": false,
      "parallel": 5
    },
    "search": {
      "top_k": 10,
      "rerank": false
    }
  },
  "aliases": {}
}

Configuration File Structure

After customization, your configuration file might look like:

{
  "api_key": "mxb_xxxxx",
  "defaults": {
    "upload": {
      "strategy": "high_quality",
      "contextualization": true,
      "parallel": 10
    },
    "search": {
      "top_k": 20,
      "rerank": true
    }
  },
  "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 set api_key $MXBAI_API_KEY

# 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

Next Steps

Now that you have the CLI configured, explore these features:

Vector Store Management

Create and manage your vector stores.

File Operations

Upload and manage documents.

Installation & Setup

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

Vector Store Management

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

Last updated: July 5, 2025

Configuration

On this page