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)
Environment variables - System environment settings (e.g., MXBAI_API_KEY, MXBAI_BASE_URL, MXBAI_CONFIG_PATH, MXBAI_DEBUG)
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.

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 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 Values

Command

mxbai config set <key> <value>

Examples

# 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 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

Deprecated: Contextualization is now configured at the store level using mxbai store create --contextualization, not per-upload. This setting is ignored by the CLI and will be removed in a future version.

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 Uploads

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 Defaults

Configure default search behavior:

Number of Results

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

Store Aliases

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 Configuration

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 Structure

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

# 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 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 store list --debug

# Via environment variable
export MXBAI_DEBUG=true
mxbai store list

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

Configuration

On this page